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CHAPTER 1 
ORGANIZATION 



This manual contains four chapters. Some of the chapters contain 
introductory or overview material that you might not need to read if you 
are already familiar with the iSBC 957B, iSDM 86, or iSDM 286 monitor. 
Other chapters contain reference material that you can use as you debug 
your system. You can use this chapter to determine which of the other 
chapters you should read. 


The remaining chapters of the manual are the following: 


Chapter 2 


Chapter 3 


Chapter A 


This chapter describes the features of the System 
Debugger and its relationship to the other tools for 
debugging iRMX 86 applications. You should read this 
chapter if you are going through the manual for the 
first time. 

This chapter gives a variety of facts pertaining to 
the use of the System Debugger. You should read this 
chapter if you are Installing the System Debugger 
and/or configuring it into your system. 

This chapter contains detailed descriptions of the 
System Debugger commands. The commands are listed in 
alphabetical order for easy referencing. When you are 
debugging your system you should refer to this chapter 
for specific Information about the format and 
parameters of the commands. 


■kit k 
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CHAPTER 2 
INTRODUCTION 


The development of almost every system requires debugging. To aid you in 
the development of iRMX 86-based application systems, Intel provides the 
1R^^ 86 Debugger, the ICE-86 In-Circuit Emulator, the ISDM 86 and 
iSDM 286 System Debug Monitors, and the iSBC 957B monitor. The System 
Debugger extends the capabilities of the three monitors. This manual 
describes the System Debugger extension. The iRMX 86 DEBUGGER REFERENCE 
MANUAL describes the IRMX 86 Debugger. The USER’S GUIDE FOR THE 
iSBC 957B lAPX 86, 88 INTERFACE AND EXECUTION PACKAGE describes the 
iSBC 957B monitor. The iSDM 86 SYSTEM DEBUG MONITOR REFERENCE MANUAL 
describes the iSDM 86 monitor. And the iSDM 286 SYSTEM DEBUG MONITOR 
REFERENCE MANUAL describes the iSDM 286 monitor. The following sections 
describe the relative advantages of the various debugging tools. 


ADVANTAGES OF THE iRMX™ 86 DEBUGGER 


The iRMX 86 Debugger is a debugging tool that is "sensitive" to the data 
structures that the Nucleus maintains. The iRMX 86 Debugger allows you 
to: 


• Manipulate or examine any task while other tasks in the system 
continue to run. This distinguishes the IRMX 86 Debugger from 
the iRMX 86 System Debugger, which requires that the application 
system be "frozen." 

• Monitor system activity without interfering with execution. 

• Examine and interpret data structures that are associated with 
the Nucleus and the Nucleus objects. 


ADVANTAGES OF THE ICE®-86 EMULATOR 

The ICE-86 emulator provides in-circuit emulation for iAPX 86, 88 
microprocessor-based systems, meaning that it "stands in" for the 8086 or 
8088 microprocessor in your target IRMX 86-based system during 
development. The ICE-86 emulator allows you to: 

• Get closer to the hardware level by examining the contents of 
input pins and input ports. 

• Change the values at output ports. 

• Examine individual components rather than an entire board. 

• Look at the most recent 80 to 150 assembly language instructions 
executed. 
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INTRODUCTION 


ADVANTAGES OF THE iSBC® 957B , ISDM'" 86, AND ISDM'' 286 MONITORS 

The ISBC 957B, iSDM 86, and iSDM 286 monitors each support both 
interactive commands and system I/O routines. Each allows you to: 

• Disassemble code. 

• Set execution and memory breakpoints. 

• Display memory. 


ADVANTAGES OF THE IRMX'" 86 SYSTEM DEBUGGER 

You can extend the capabilities of the iSBC 95 7B, iSDM 86, or iSDM 286 
monitor the System Debugger part of your operating system. In addition 
to retaining the features of the monitors, the System Debugger; 

• Identifies and interprets IRMX 86 system calls. 

• Displays iR^DC 86 objects. 

• Examines the stack of a task to determine which IRJ^ 86 system 
calls it has made recently. 


REQUIREMENTS OF THE iRMX'" 86 SYSTEM DEBUGGER 


In order to use the System Debugger, you must have exactly one of the 
following hardware configurations, with whatever support hardware that is 
required (independent of the System Debugger); 

• A terminal connected directly to an iAPX 86-, 88-, 186-, 188-, or 
286-based board. 


• An Intellec system connected to an iAPX 86-, 88-, 186-, 188-, or 
286-based board. 

You must also have: 

• The monitor portion of the iSBC 957B iAPX 86, 88 Interface and 
Execution Package or the iSDM 86 or iSDM 286 System Debug Monitor. 

• At least the minimal configuration of the Nucleus. The System 
Debugger needs only a small portion of valid Nucleus code, so 
most of the System Debugger commands will function even if you 
accidentally write over part of the Nucleus. 

See the next chapter for more information about configuring and 
installing the System Debugger. 
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CHAPTER 3 
USING THE SYSTEM DEBUGGER 


This chapter contains various facts about using the iRMX 86 System 
Debugger. 


HOW THE SYSTEM DEBUGGER IS SUPPLIED 


The System Debugger is supplied as a file along with the other parts of 
the iRMX 86 Operating System. 


USE RESTRICTIONS OF THE SYSTEM DEBUGGER 


One of the capabilities of the System Debugger is that it can display 
information about specific invocations of system calls. However, it can 
do this correctly only for applications that use the PL/M-86 SMALL, 
COMPACT, or LARGE model of segmentation. 


CONFIGURING THE SYSTEM DEBUGGER 


To use the System Debugger to debug your application, you must configure 
it into the application. You do this simply by responding to two prompts 
that the iRMX 86 Interactive Configuration Utility issues. One of the 
prompts asks whether 3rou want the System Debugger to be part of your 
system. The other, which applies only if you respond affirmatively to 
the first prompt, asks which Interrupt level you want to use to invoke 
the System Debugger manually. 


INVOKING THE SYSTEM DEBUGGER 


There are two ways of invoking the System Debugger. As the previous 
section implies, one way is to press the button that is physically tied 
to the Interrupt level you specify during configuration. The other way, 
which requires that your system Include the Human Interface, is to use 
the DEBUG command. 
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USING THE SYSTEM DEBUGGER 


The DEBUG command syntax requires the pathname of a loadable file. DEBUG 
loads the indicated file and then passes control to the iSBC 957B, iSDM 
86, or iSDM 286 monitor. Normally, the file the DEBUG command loads is 
the file that is to be debugged. However, in this case the file to be 
debugged (the application system incorporating the System Debugger) is 
already in memory. To satisfy the requirement that the DEBUG command 
load some file, but without corrupting your application, specify the 
pathname of a file that the DEBUG command can load harmlessly into an 
area of memory not used by the application. A file you can use for this 
purpose is the TIME command of the Human Interface. It requires little 
memory and, when loaded, is automatically located where it does not 
interfere with the application. 

See the iRMX 86 OPERATOR'S MANUAL for more information concerning the 
DEBUG command. 

After the DEBUG command loads the file into memory or after you press the 
interrupt button, the monitor issues its period (.) prompt, and you can 
begin entering System Debugger commands. These commands are the subject 
of the next chapter. 


RETURNING TO YOUR APPLICATION 


When you have finished debugging your application system, you can start 
it up again by means of the go (G) command of the monitor. 
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CHAPTER 4 
COMMANDS 


This chapter contains detailed descriptions of the JJRMX 86 System 
Debugger commands, in alphabetical order. There is also a Command 
Dictionary that lists the commands in functional groups. 

This chapter uses "CS:IP" to mean "code segment: Instruction pointer." 

The chapter also contains several examples of System Debugger commands 
entered at the terminal. In the examples, user input is underscored to 
distinguish it from System Debugger output. Carriage returns are not 
shown after the user input but they are required, for the System Debugger 
to execute the command. 


CHECKING VALIDITY OF TOKENS 

The iRMX 86 Operating System maintains tokens in doubly-linked lists. 

Whenever you enter a command that requires a token as a parameter, the 
System Debugger checks the validity of that token by looking at the 
token's forward and backward links. It checks tokens that you enter as 
parameters for the VD, VK, VJ, VO, VR, VT, and VU commands as well as the 
tokens that are listed in the displays. 

If one of a token's links is bad, the System Debugger generates an error 
message along with the information the command that you entered usually 
displays. The token you enter as a parameter of the System Debugger 
command always appears in each line as the center value in the display of 
tokens. The displays for forward- and backward-link errors are as 
follows : 

Forward link ERROR: 4111-->4E85 41 1 1<— 4E8 5— >4155 ?FFFF<— 4155 

Back link ERROR: 4111— >410F? 411 K—4E85— >4155 4E85<— 4155 

Arrows to the right indicate forward links and those to the left indicate 
backward links. A question mark appearing before or after a value 
signals a forward or backward link error. 

If both links are bad, the System Debugger considers the token invalid 
and displays the following message: 

*** INVALID TOKEN *** 
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COMMANDS 


The presence of a link error means that iRMX 86 data structures have been 
corrupted. The most common reason for this problem is overwriting. One 
of your tasks might have accidentally written over part of the system 
data structures and/or code. If you are using the non-maskable 
interrupt, another possible cause of a link error is that you Interrupted 
the Nucleus while it was setting up the links. If either of these things 
happen, you must re-inltiallze the System Debugger (and perhaps your 
System). Only then can you use the VD, VJ, VK, VO, VR, VT, and VU 
commands without getting another link error. See Chapter 3 in this 
manual for more information about initializing the System Debugger on 
your system. 


PICTORIAL REPRESENTATION OF SYNTAX 


This manual uses a schematic device to illustrate the syntax of 
commands. The schematic consists of what looks like an aerial view of a 
model railroad, with syntactic elements scattered along the track. 
Imagine that a train enters the system at the far left, drives around as 
much as it can or wants to (sharp turns and backing up are not allowed), 
and finally departs at the far right. The command it generates in doing 
so consists of the syntactic elements that it encounters on its journey. 
The following pictorial syntax shows two valid sequences: AC and BC. 



x-455 


The pictorial syntax of the commands in this chapter does not show spaces 
as elements. However, the SDB does allow one or more spaces between the 
command and the parameter. For example., even though the syntax for VR is 


you can enter: 
.VR XXX X 




The space between "VR" and "xxxx" does not affect the result of the 
command. 

Even though all syntax diagrams show uppercase letters, such as VR, 
entering lowercase equivalents of those letters produces the same effect. 


DISPLAY OF NUMERICAL VALUES 


In all of the displays that this chapter discusses, all mmierical values 
are given in hexadecimal form. 
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COMMANDS 


COMMAND DICTIONARY 

Command Page 

DISPLAYING IRMX 86 DATA STRUCTURES 

VD — Display a Job’s Object Directory..... 4-7 

VJ — Display the Job Hierarchy.. 4-12 

VK — Display Ready and Sleeping Tasks...... 4-15 

VO — Display the Objects in a Job 4-17 

VR--Dlsplay an I/O Request/Result Segment 4-20 

VT — Display an IRMX 86 Object....... 4-29 

RECOGNIZING AND DISPLAYING iRMX 86 SYSTEM CALLS 

VC — Display System Call Information 4-4 

VS — Display Stack and System Call Information 4-24 

VU — Display System Calls in Task’s Stack 4-48 

OTHER COMMANDS 

VH--Display Help Information..... 4-10 
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COMMANDS 


VC-DISPLAY SYSTEM CALL INFORMATION 


VC — Display System Call Information 


The VC command checks to see if a CALL instruction is an iRMX 86 system 
call. 



PARAMETER 

pointer The optional pointer parameter can be any valid 

iSBC 95 7B, ISDM 86, or iSDM 286 address. The 
System Debugger uses this address as the address 
of the CALL instruction to be checked. 

If you do not supply a pointer, the System Debug 
Monitor uses the default pointer, which is the 
current CS:IP. If you specify an IP value but 
not a CS value, the System Debugger uses the 
current CS as the default base. 


DESCRIPTION 

If the CALL instruction is an IRMX 86 system call, the VC command 
displays information about the CALL Instruction as shown in Figure 4-1. 


S/W int: xx (subsystem) entry code xxxx system call 


Figure 4-1. Format Of VC Output 


The fields in Figure 4-1 are defined as follows: 

S/W int: xx (subsystem) The software interrupt number and the 

IRMX 86 subsystem that corresponds to 
that number. 

entry code xxxx The entry code for the system call 

within the subsystem. 

system call The name of the IRMX 86 system call. 
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VC-DISPLAY SYSTEM CALL INFORMATION 


NOTE 

The System Debugger uses the software 
interrupt number associated with the 
displayed entry code to determine 
whether the CALL instruction represents 
a system call. It is possible, but not 
likely, that the System Debugger can 
interpret a sequence of bytes as a 
software interrupt (INT) instruction 
and then (inaccurately) reported that a 
CALL instruction is an iRMX 86 system 
call. 


ERROR MESSAGES 


The System Debugger returns the following error messages for the VC 
command: 


Error Message 


Description 


Syntax Error You made an error in entering the command. 

Not a system CALL The parameter you specified points to a CALL 

Instruction that is not an iRMX 86 system 
call. 


Not a CALL instruction The parameter you specified does not point 

to any kind of call instruction. 



EXAMPLES 


Suppose you disassembled the following code using the DX command of the 
iSBC 957, iSDM 86, or iSDM 286 monitor: 


49A4:006D 

50 

PUSH 

AX 


49A4:006E 

E8AD1E 

CALL 

A = IFIE 

;$+7856 

49A4:0071 

E8DD03 

CALL 

A = 0451H 

;$+992 

49A4:0074 

B80000 

MOV 

AX,0 


49A4:0077 

50 

PUSH 

AX 


49A4:0078 

8D060600 

LEA 

AX, WORD PRT 

00 6H 

49A4:007C 

IE 

PUSH 

DS 


49A4:007D 

50 

PUSH 

AX 


49A4:007E 

E8411E 

CALL 

A = 1EC2H 

;$+7748 

49A4:0081 

A30000 

MOV 

WORD PTR 000 OH, AX 


If you use the VC command on the CALL instruction at address 49A4:006E, 
that is, you enter: 

.VC 49A4:006E 
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COMMANDS 


VC-DISPLAY SYSTEM CALL INFORMATION 


the System Debugger responds by displaying the following information: 

S/W Int: B8 (Nucleus) entry code 0801 set exception handler 

The "S/W Int: B8 (Nucleus)" means that the software interrupt number, 
"B8", identifies this call as a Nucleus call. The entry code within the 
Nucleus is "0801" which corresponds to an RQ$SET$EXCEPTION$HANDLER system 
call. 

Now suppose you want to see if the CALL instruction at 49A4:0071 is a 
system call. Enter: 

. VC 49A4:0071 

The System Debugger responds with the following message. 

Not a system CALL 

Finally, if you use the VC command on the Instruction at 49A4:0074, the 
System Debugger responds with: 

Not a CALL instruction 
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VD--Display A Job’s Object Directory 

The VD command displays a job’s object directory. 



x-458 

The token for the job whose object directory you 
want to display. 

DESCRIPTION 

If the parameter is a valid job token, the System Debugger displays the 
job’s object directory, as shown in Figure 4-2. 


0 

c 


xxxx Entries used: xxxx 

token ]_ 

tasks waiting token 2 . • • token^ 

• 

token j 
token^^ 

token^ 

Figure 4-2. Format Of VD Output 
The fields in Figure 4-2 are as follows: 


Directory size: 

name 2 
name 2 


namej 

invalid entry 
name]^ 


name« 


PARAMETER 

job token 
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COMMANDS 


VD-DISPLAY A JOB’S OBJECT DIRECTORY 


Directory size 


The maximum allowable number of entries this 
job can have in its object directory. 


Entries used 

namex* • .name^i^ 
tokenx • • • token^^^ 
tasks waiting 


invalid entry 


The number of entries used presently in the 
directory. 

The names under which objects are cataloged. 

Tokens for the cataloged objects. 

Signifies that one or more tasks have 
performed an RQ$L00KUP$0 EJECT on an object 
that is not cataloged. The tokens following 
this field identify the tasks that are still 
waiting for the objects to be cataloged. 

This field appears only if the specified 
job’s object directory has been destroyed or 
written over. 


ERROR MESSAGES 


The System Debugger returns the following error messages for the VD 
command: 


Error Message Description 

Syntax Error You did not specify a parameter for the 

command, or you made an error in entering 
the command. 


TOKEN is not a Job 


You entered a valid token that is not a job 
token. 


*** INVALID TOKEN *** 


The value you entered for the token is not a 
valid token. 
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VD DISPLAY A JOB’S OBJECT DIRECTORY 


EXAMPLES 


If you want to look at the object directory of job "528F," you can enter: 
.VD 528F 


The System Debugger responds as follows: 

Directory size: OOOA Entries used: 0003 

$ 5229 

R?I0USER 5201 

RQGLOBAL 528F 

The S3mibols "R7I0USER," and "RQGLOBAL” are the names of the objects, 

and their respective tokens are 5229, 5201, and 52 8F. There are no 
waiting tasks or invalid entries. 
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COMMANDS 


VH-DISPLAY HELP INFORMATION 


VH — Display Help Information 


The VH command displays and describes the ten System Debugger commands. 



x-459 


PARAMETERS 


There are no parameters for this call. 


DESCRIPTION 


The VH command lists all of the System Debugger commands, along with 
their parameters and a short description of each command. 

ERROR MESSAGE 

The System Debugger returns the following error message for the VH 
command: 

Error Message Description 

Syntax Error You made an error in entering the command. 

EXAMPLE 
If you enter: 

. VH 

the System Debugger responds as shown in Figure 4-3, where the brackets 
indicate optional parameters. 
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VH-DISPLAY HELP INFORMATION 


URMX 86 SYSTEM DEBUGGER, Vx.y 


VC 

[ <P0INTER> ] 

Display 

vd 

<Job T0KEN> 

Display 

vh 


Display 

vj 

[<Job T0KEN>] 

Display 

vk 


Display 

VO 

<Job T0KEN> 

Display 

vr 

<Seg T0KEN> 

Display 

vs 

[ <Count> ] 

Display 

vt 

<T0KEN> 

Display 

vu 

<Task T0KEN> 

Display 



Figure 


system call, 

job's object directory. 

help information. 

job hierarchy from specified level. 

ready and sleeping tasks. 

list of objects for specified job. 

I/O Request/Result Segment, 
stack and system call information. 
iRMX 86 object. 

system calls on stack of specified task. 


4-3. VH Display 


NOTE 

If you use zero (0) for any of the 
optional parameters shown in Figure 
4-3, the effect is the same as if you 
omitted the parameter altogether. 
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COMMANDS 


VJ DISPLAY JOB HIERARCHY 


VJ — Display The Job Hierarchy 


The VJ command displays the portion of the job hierarchy that descends from 
the level you specify. 



x-460 


PARAMETER 

job token The token for the job whose descendant job hierarchy you 

want to display. 

If you do not specify a job token, VJ assumes the 
default job, which is the root job. 

The specified job, vfhether it is specified explicitly or 
whether it is the default (root) job, should not have 
more than 44 generations of job descendants. Otherwise, 
the display of the excessive ly-long branch is 
discontinued, an error message is displayed, and the 
System Debugger prompts for another command. 


DESCRIPTION 


The VJ command displays the token of the specified job and all the tokens 
of its descendant jobs. It also displays the tokens of the jobs (and their 
descendants) at the same level as the specified job. The descendant jobs 
are indented three spaces to show their position in the hierarchy. This 
command displays the job hierarchy as shown in Figure 4-4. 


iRMX/86 Job Tree 

token 

token2 

token3 

token4 

token5 

token^ 


Figure 4-4. Format Of VJ Output 
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VJ-DISPLAY JOB HIERARCHY 


The fields in Figure 4-4 are as follows: 

tokenj^ The token for the root job or the job you 

specify. 

t oken 2 « . • token^ The tokens for the descendant jobs of the root 

job or the job you specify. 

In Figure 4-4, jobs 2 and 6 are both indented three spaces to signify that 
they are children of job 1. Similarly, jobs 3 and 5 are depicted as 
children of job 2, and job 4 is shown as the child of job 3. 


ERROR MESSAGES 


The System Debugger returns the following error messages for the VJ command: 


Error Message 
Syntax Error 
TOKEN is not a Job 

*** INVALID TOKEN *** 


Description 


You made an error in entering the command. 

You entered a valid token that is not a job 
token. 

The value you entered for the token is not a 
valid token. 


Error looking for The System Debugger cannot find the root job. 

root job 


SDB job nest limit The job specified in the command invocation (or 

exceeded the default job) has more than 44 generations 

of job descendants. 



EXAMPLES 


If you want to examine the hierarchy of the root job, enter: 

. VJ 

Suppose the System Debugger responds with the following job tree. 
lRMX/8 6 Job Tree 


57DE 
528F 
5 ICE 
4F9F 

5741 

57B5 

The display shows "5 7DE" to be the root job. 
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VJ-DISPLAY JOB HIERARCHY 


If you want to display the descendant jobs of "5 ICE", enter: 
.VJ 5 ICE 


The System Debugger displays the following job tokens: 

5 ICE 
4F9F 


NOTE 

The VJ command (without a parameter) 
requires the Nucleus Interrupt vector 
and a small part of the Nucleus code in 
order to function correctly. If you 
destroy the Nucleus interrupt vector 
(by pressing the RESET switch) or if 
you write over the required part of 
Nucleus code, this command does not 
operate properly. You must 
re-inltiallze your system in order to 
restore the VJ command. 
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VK-DISPLAY READY AND SLEEPING TASKS 


VK — Display Ready And Sleeping Tasks 


The VK command displays the tokens for the tasks that are in the ready 
and sleeping states. 
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PARAMETERS 


This command has no parameters. 


DESCRIPTION 


The VK command displays the tokens for the tasks that are ready and 
asleep, in the format shown in Figure 4-5. 


Ready tasks: xxxx 

Sleeping tasks: xxxx 



Figure 4-5. Format Of VK Output 


The fields in Figure 4-5 are as follows: 

Ready tasks The tokens for all ready tasks in the system. 

Sleeping tasks The tokens for all sleeping tasks in the 

system. 

ERROR MESSAGES 

The System Debugger returns the following error messages for the VK 
command: 
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COMMANDS 


VK-DISPLAY READY AND SLEEPING TASKS 


Error Messages 


Description 


Ready tasks; Can't locate 
Sleeping tasks: 

Can't locate 


The system is corrupted. See the 
following explanation. 


Syntax error 


You made an error in entering the 
command. 


The System Debugger uses the Nucleus interrupt vector and some Nucleus 
code in order to identify the ready and sleeping tasks. If you somehow 
destroy the Nucleus interrupt vector or the required code, the System 
Debugger can't identify the ready and sleeping tasks. 

The most common reasons for this type of error are; 

• Pressing the R13SET switch during debugging. 

• Not initializing the Nucleus interrupt vector. 

• Tasks writing over the Nucleus code. 

• Tasks writing over iRMX 86 objects. 

If any of these problems apply to your system, you must r e-initialize 
your system. 


EXAMPLE 

If you want to display a list of all the ready and sleeping tasks in your 
system, enter; 

.VK 

In this example, the System Debugger responds as follows: 


Ready tasks: 4F02 

Sleeping tasks: 56F5 

558A 

56BF 

5204 

51B3 

5090 

55EC 

5052 

5021 

4FFE 

5697 

5238 

511F 

56 6E 

56 3A 

5769 

50D1 

2302 
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VO-DISPLAY THE OBJECTS IN A JO 


E 


VO — Display Objects In A Job 


The VO command displays the tokens for the objects in a job. 



PARAMETER 

job token The token for the job whose objects you want to 

display. 


DESCRIPTION 


The VO command lists the tokens for a job's child jobs, tasks, mailboxes, 
semaphores, regions, segments, extensions, and composites in the format 
shown in Figure 4-6. 


Child jobs: 

XX XX 

xxxx 

xxxx 


Tasks : 

xxxx 

xxxx 

xxxx 


Mailboxes: 

xxxx 

xxxx 

xxxx 


Semaphores : 

xxxx 

xxxx 

xxxx 


Regions: 

xxxx 

xxxx 

xxxx 


Segment s : 

xxxx 

xxxx 

xxxx 


Extensions: 

xxxx 

xxxx 

xxxx 


Composites : 

xxxx 

xxxx 

xxxx 



Figure 

4-6. Format Of 

VO Output 



The fields in Figure 4-6 are as follows: 


Child jobs 


The tokens for the specified job's offspring 
jobs. 


Tasks 


The tokens for the tasks in the specified 
job. 
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Mailboxes The tokens for the mailboxes within the 

job. A lower-case "o" immediately following 
a mailbox token means that one or more 
objects are queued at the mailbox. A 
lower-case "t" immediately following a 
mailbox token means that one or more tasks 
are queued at the mailbox. 

Semaphores The tokens for the semaphores in the 

specified job. A lower-case "t" immediately 
following a semaphore token means that one 
or more tasks are queued at the semaphore. 

Regions The tokens for the regions in the specified 

job. A lower-case "b" (busy) immediately 
following a region token means that a task 
has access to information guarded by the 
region. 

Segments The tokens for the segments in the specified 

job. 

Extensions The tokens for the extensions in the 

specified job. 

Composites The tokens for the composites in the 

specified job. 


ERROR MESSAGES 


The System Debugger returns the following error messages for the VO 
command 


Error Message 


Description 


Syntax Error You did not specify a parameter for the 

command or you made an error in entering the 
command. 


TOKEN is not a Job You entered a valid token that is not a job 

token. 

*** INVALID TOKEN *** The value you entered for the token is not a 

valid token. 


EXAMPLE 

Suppose you want to look at the objects in "5 ICE. 
.VO 5 ICE 
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The System Debugger responds with the following display: 
Child jobs: 4F9F 


Tasks: 

5UF 

50D1 

5090 

5052 

5021 

4FFE 

Mailboxes : 

5119 

5110 

5100 t 

50FB t 

50CE t 

5089 t 

Semaphores: 
Regions : 

50FE 

501F t 





Segments: 

Extensions: 

5 IOC 

5103 

508C 

504E 

4FE6 

4FCB 

Composites: 

511C 

5113 

50C8 

5083 

4FF3 

4FED 


The previous display shows the tokens for the child jobs, tasks, 
mailboxes, semaphores, regions, segments, extensions, and composites in 
the job. It also tells you that there are tasks waiting at four 
mailboxes and at one semaphore. 
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VR — Display I/O Reques t/Result Segment 


The VR command displays Information about the iRMX 86 Basic I/O System 
I/O reques t/ result segment (lORS) that corresponds to the segment token 
that you enter. 

0 — 

x-463 


PARAMETER 


Segment token The token for a segment containing the TORS you 

want to display. This segment must be an lORS or 
the VR command returns Invalid information. 


DESCRIPTION 

The VR command displays the names and values for the fields of a specific 
lORS. The System Debugger cannot determine whether the segment contains 
a valid lORS, so it is up to you to ensure that the segment does indeed 
contain an lORS. If the parameter is a valid segment token for a segment 
containing an lORS, the System Debugger displays information about the 
lORS as shown in Figure 4-7. 

The contents of the lORS pertain to the most recent I/O operation in 
which this lORS was used. For more information concerning the following 
fields, see the GUIDE TO WRITING DEVICE DRIVERS FOR THE iRMX 86 AND 
IRMX 88 I/O SYSTEMS. 


I/O Request Result Segment 


Status 

Device 

Function 

Count 

Device location 
Resp mailbox 
Link forward 
Done 

Connection token 


xxxx 

xxxx 

xxxxx 

xxxxxxx 

xxxxxxxx 

xxxx 

xxxx: xxxx 

xxxx 

xxxx 


Unit status 
Unit 

Subfunction 

Actual 

Buffer pointer 
Aux pointer 
Link backward 
Cancel ID 


xxxx 

XX 

xxxxxxx 

xxxx 

xxxx: xxxx 
xxxx: xxxx 
xxxx: xxxx 
xxxx 


Figure 4-7. Format Of VR Output 
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The fields in Figure 4-7 are as follows: 


Status 


Unit status 


Device 


Unit 


Function 


Subfunction 


The condition code for the I/O operation. 

See the description of I/O Request /Result 
Segments in the iRMX 86 BASIC I/O SYSTEM 
REFERENCE MANUAL for further information. 

Additional status Information. The contents 
of this field are meaningful only when the 
Status field is set to the E$IO condition 
(002BH). 

See the description of I/O Request/Result 
Segments in the IRMX 86 BASIC I/O SYSTEM 
REFERENCE MANUAL for further information. 

The number of the device for which the last 
request was intended. 

The number of the unit for which this request 
was intended. 

The operation that was performed by the Basic 
I/O System, The possible functions are as 
follows: 


Function 

System Call 

Read 

RQ$A$READ 

Write 

RQ$A$WRITE 

Seek 

RQ$A$SEEK 

Special 

RQ$A$SPECIAL 


Att Dev 

RQ$A$PHYSICAL$ATTACH$DEVICE 

Det Dev 

RQ$A$PHYSICAL$DETACH$DEVICE 

Open 

RQ$A$OPEN 

Close 

RQ$A$CLOSE 


If the function field contains an invalid 
value, the System Debugger displays the 
value in this field, followed by a space and 
two question marks. 

A further specification of the function that 
applies only when the Function field 
contains "Special. " The possible 
subfunctions and their descriptions are as 
follows: 
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Subfunction (con’t) 


Count 

Actual 

Device location 


Buffer pointer 


Resp mailbox 
Aux pointer 


Link forward 
Link backward 


Done 


Subfunction 
For/Que 
Satisfy 
Notify 
Device char 
Get Term Attr 
Set Term Attr 
Signal 
Rewind 

Read File Mark 
Write File Mark 
Retention Tape 


Description 

Format or Query 

Stream file satisfy function 

Notify function 

Device characteristics 

Get terminal attributes 

Set terminal attributes 

Signal function 

Rewind tape 

Read file mark on tape 
Write file mark on tape 
Take up slack on tape 


If the Function field doesn't contain 
"Special", then the Subfunction field 
contains "N/A." If the Subfunction field 
contains an invalid value, the System 
Debugger displays the value of the field 
followed by a space and two question marks. 


The number of bytes of data called for in the 
I/O request. 

The number of bytes of data transferred in 
response to the request. 

The eight-digit hexadecimal address of the 
byte where the I/O operation began on the 
specified device. 


The address of the buffer from which the 
Basic I/O System read or to which it wrote in 
response to the request. 

A token for the response mailbox to which the 
device sent the TORS after the operation. 

The pointer to the location of auxiliary 
data, if any. This field is significant only 
when the Function field contains "Special. " 

The address of the next lORS in the queue 
where the lORS waited to be processed. 

The address of the previous lORS in the queue 
where the lORS waited to be processed. 

This field is always present but applies only 
to lORS's for I/O operations on random-access 
devices. When applicable, it indicates 
whether the I/O operation has been 
completed. The possible values are TRUE 
(FFFFH) and FALSE (OOOOH). 
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Cancel ID 
Connection token 

ERROR MESSAGES 

The System Debugger returns 
command: 

Error Message 

Syntax Error 

token is not a Segment 

*** INVALID TOKEN *** 

Segment wrong size, 
not an lORS 


A word that Is used by device drivers to 
Identify I/O requests that need to be 
cancelled. A value of 0 indicates a request 
that cannot be cancelled. 

The token for the file connection that was 
used to issue the request for the I/O 
operation. 


the following error messages for the VR 


Description 

You did not specify a parameter for the 
command or you made an error In entering the 
command. 

You entered a valid token that is not a 
segment token. 

The value you entered for the token is not a 
valid token. 

The specified segment is neither four nor five 
paragraphs in length, so it is not an I/O 
request/result segment. 
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vs — Display Stack And System Call Information 


The VS command identifies system calls (as does the VC command) and 
displays the stack. 


x-464 


A decimal or hexadecimal value that specifies the 
number of words from the stack that are to be 
included in the display. A suffix of T, as in 
16T, means decimal. No suffix or a suffix of H 
indicates hexadecimal. 

If you do not specify a count, VS assumes the 
default value, lOH. 


DESCRIPTION 

The VS command identifies IRMX 86 system calls for all iRMX 86 subsystems 
(as does the VC command) and interprets the parameters on the stack. If 
a parameter is a string, the System Debugger displays the string. See 
the appropriate iRMX 86 manual for additional Information about system 
calls. 

The VS command interprets the CALL instruction at the current CS:IP. If 
you want to interpret a CALL instruction at a different CS:IP value, you 
must move the CS:IP to that value by using the iSBC 957B , iSDM 86, or 
iSDM 286 GO command. 

The VS command uses current values of the SS:SP (stack segment: stack 
pointer) registers to display the current stack values. If the 
instruction is an IRMX 86 system call, VS displays the system call and 
the stack information, as shown in Figure 4-8. 


PARAMETER 

count 
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xxxx: xxxx 
xxxx:xxxx 


xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx 

xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx 


S/W int: 


XX (subsystem) 


entry code xxxx system call 


:parameters. : 


Figure 4-8, Format Of VS Output 


The fields in Figure 4-8 are as follows: 


xxxx: xxxx 


The contents of the SS:SP. 


xxxx 


Stack values. 


parameters The names of the stack values. The 

parameters correspond to the stack values 
directly above them. 

The three remaining fields in Figure 4-8 are identical to those in the VC 
command. 

S/W int: xx (subsystem) The software Interrupt number and the 

IRMX 86 subsystem that corresponds to that 
number. 

entry code xxxx The entry code for the system call within 

the subsystem. 

system call The name of the iRMX 86 system call. 



ERROR MESSAGES 


The System Debugger always displays the words at the top of the stack. 

If it encounters problems, it then returns one of the following error 
messages. 

Error Message Description 

Syntax Error You made an error in entering the command. 

Not a system CALL The CS:IP is pointing to a CALL instruction 

that is not a system call. 
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Unknown entry code This message indicates that one of two 

infrequent events has occurred. One is that 
the System Debugger has mistaken an operand 
for the software interrupt (INT) 
instruction. The other possibility is that 
a software link from user code into iRtiX 86 
code has been corrupted. 

If the instruction is not a CALL instruction, VS displays the contents of 
the words on the stack and no message. 


EXAMPLES 


Suppose that by some means, such as the X command of the iSBC 957B , 
iSDM 86, or iSDM 286 monitor, you determine that the SS:SP is 4906:07CA. 
Suppose further that you then you use the VS command, as follows: 

.VS 


4906:07CA 

4906:07DA 

0008 

49A4 

4984 

0020 

4EAC 

2581 

4983 

4EAC 

4983 0000 0600 

4EA1 4EE7 0000 

4906 

0000 

S/W int: B8 

(Nucleus) 

entry code 

0301 

delete mailbox 



: . .exce 

p$p. . : 

.mbox. : 





The parameter names identify the stack values directly above them. That 
is, the "excep$p" parameter name signifies that the first two words 
represent a pointer (4984:0008) to the exception code. Similarly, the 
"mbox" parameter signifies that the third word (4EAC) is the token for 
the mailbox being deleted. 

Now, suppose that you move the SS:SP to 4906:07D0. If you Invoke the VS 
command now, the debug monitor displays the stack as follows: 

. VS 

4906:07D0 4983 4983 0000 0600 4906 49A4 0020 2581 

4906:07E0 F7C7 F7C7 F5C7 F5C7 F5C7 F5C7 F5CF F5CF 

Not a system CALL 

The System Debugger displays the stack and a message which Informs you 
that the instruction is a CALL instruction but is not a system call. 

When an iRMX 86 system call is executed, its parameters are pushed onto 
the current stack, and then a CALL instruction is issued with the 
appropriate address. If you want to display the stack at such a call 
when there are more parameters than will fit on one line, the System 
Debugger automatically displays multiple lines of words from the stack, 
with corresponding lines of parameter description directly below them. 
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For example, suppose that you use the VS command as follows: 
.VS 


57CC:0F9A 

015A 60C7 

0000 

60C6 

60C6 

0000 

0600 

57CC 

57CC:0FAA 

60EF 0028 

2322 

0000 

60C7 

6618 

6605 

6623 

57CC:0FBA 

6609 5A5F 

5AF8 

660B 

0000 

0000 

0000 

0000 

S/W Int: B8 

(Nucleus) entry code 

0100 

create job 




: . . .excep$p. . 

. :t$f Igs: s tksze: 

..sp.. :..ss.. 

CO 

• 

• 

.:..lp 


: • ,cs. • : .pri. • : j$flgs: .exp$inf o$p. . :maxpr i:maxtsk:maxob j : 
:poolmx: poolmn: param. rdirsiz: 


This display indicates that the CALL instruction is a Nucleus 
RQ$CREATE$ JOB system call having 18 parameters. The names of these 
parameters are shown between the colons (:). As usual, the words on the 
stack correspond to the parameters shown directly below those words. 

The following display indicates that the CALL instruction is a Basic I/O 
System (BIOS) RQ$A$ATTACH$FILE system call having five parameters. The 
"subpath$p‘* parameter points to a string that is seven characters long. 
This string consists of the word "example." 

. VS 

57CC:0F4E 0F8C 57CC 65FD 0000 6600 69A2 0000 6602 

57CC:0F5E 660B 3C13 6602 2325 66D2 0F7C 0DF7 FFFF 

S/W Int: CO (BIOS) entry code 0002 attach file 

: . . .excep$p. . . : .mbox. : . . subpath$p. . :pref ix: .user. : 
subpath — >07 'example' 



The following display indicates that the CALL instruction at CS:IP is an 
Extended I/O System RQ$S$RENAME$FILE system call having three 
parameters. There are two parameters with strings in this example. The 
new$path$p parameter points to a string that is four characters long. 
This string contains "XY70. " The path$p parameter points to a string 
that is also four characters long and contains "temp." 

. VS 

57CC:0F98 014A 60C7 06A5 60EF 06A5 60EF 0000 0600 

57CC:0FA8 57CC 60EF 0028 2322 0000 60C7 OOOA 6605 

S/W Int: Cl (EIOS) entry code 0108 rename file 

: . . .excep$p. . . : .new$path$p. . : . . .path$p. . . . : 
new path — >04'XY70' 
path — >04' temp ' 
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NOTE 

If a string is more than 50 characters 
in length, the System Debugger will 
display only the first 50 characters of 
the string. And if the pointer to a 
string is 0000:0000,, the System 
Debugger does not display the string. 
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VT — Display An iRMX 86 Object 

The VT command displays information about the iRMX 86 object associated 
with the token you enter. 



x-465 


PARAMETER 

token The token for the object for which the 

System Debugger will display Information. 


DESCRIPTION 


The VT command ascertains the type of object represented by the token and 
displays Information about that object. Both the information and the 
format in which the System Debugger displays the Information depend 
entirely upon the type of the object. The following sections are divided 
into display groups. Each display group illustrates the format of the 
display for a particular type of object. 



ERROR MESSAGES 


The System Debugger returns the following error messages for the VT 
command 

Error Message Description 

Syntax Error You did not specify a parameter for the 

command or you made an error in entering the 
command. 

*** INVALID TOKEN *** The value you entered for the token is not a 

valid token. 


JOB DISPLAY 


If the parameter that you supply is a valid job token, the System 
Debugger displays information about the job that has that token, as 
Figure 4-9 shows. 
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Object type = 1 Job 


Current tasks 

xxxx 

Max tasks 

xxxx 

Max priority 

XX 

Current objects 

XXX X 

Max objects 

xxxx 

Parameter obj 

xxxx 

Directory size 

xxxx 

Entries used 

xxxx 

Job flags 

xxxx 

Except handler 

xxxx: xxxx 

Except mode 

XX 

Parent job 

xxxx 

Pool min 

xxxx 

Pool Max 

xxxx 

Initial size 

xxxx 

Pool size 

xxxx 

Allocated 

xxxx 

Largest seg 

xxxx 


Figure 4-9. Format Of VT Output (Job Display) 


The fields in Figure 4-9 are as follows: 


Current tasks 
Max tasks 


Max priority 


Current objects 


Max objects 


Parameter obj 


Directory size 


Entries used 


The number of tasks currently existing in the job. 

The maximum number of tasks that can exist in the 
job at the same time. This value was set when 
the job was created with the RQ$CREATE$JOB system 
cal 1. 

The maximum (numerically lowest) priority allowed 
for any one task in the job. This value was set 
when the job was created. 

The number of objects currently existing in the 
job. 

The maximum number of objects that can exist in 
the job at the same time. This value was set 
when the job was created. 

The token for the object that the parent job 
passed to this job. This value was set when the 
job was created. 

The maximum number of entries the job can have in 
its object directory. This value was set when 
the job was created. 

The number of objects currently cataloged in the 
job’s object directory. 


Job flags The job flags parameter that was specified when 

the job was created. 

Except handler The start address of the job’s exception 

handler. This address was set when the job was 
created. 


System Debugger 4-30 





VT-DISPLAY iRMX™ 86 OBJECT 


Except mode 

Parent job 
Pool min 

Pool max 

Initial size 
Pool size 
Allocated 
Largest Seg 


The value that indicates when control is to be 
passed to the new job's exception handler. This 
value was set when the job was created. 

The token for the job’s parent. 

The minimum size (in 16-byte paragraphs) of the 
job's memory pool. This value was set when the 
job was created. 

The maximum size (in 16-byte paragraphs) of the 
job's memory pool. This value was set when the 
job was created. 

The initial size (in 16-byte paragraphs) of the 
job's memory pool. 

The current size (in 16-byte paragraphs) of the 
job's memory pool. 

The number of currently-allocated 16-byte 
paragraphs in the job's memory pool. 

The number of 16-byte paragraphs in the largest 
contiguous portion of the job's memory pool. 


TASK DISPLAY 


The System Debugger displays information about tasks in two different 
ways. The first display is for non-interrupt tasks and the second is for 
interrupt tasks. The format of the two types of tasks is shown in 
Figures 4-10 and 4-11, 



object type = 2 Task 


Static pri xx 
Suspend depth xx 
Except handler xxxxtxxxx 
Containing job xxxx 


Dynamic pri xx 

Delay req xxxx 

Except mode xx 

Interrupt task no 


Task state xxxx 

Last exchange xxxx 

Task flags xx 

Kernel saved ss:sp xxxxtxxxx 


Figure 4-10. Format Of VT Output (Non-Interrupt Task) 
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object type = 2 Task 


Static pri 

XX 

Dynamic pri 

XX 

Suspend depth 

XX 

Delay req 

xxxx 

Except handler 

xxxx: xxxx 

Except mode 

XX 

Containing job 

xxxx 

Interrupt task 

yes 

Master mask 

XX 

Slave mask 

XX 

Pending int 

XX 

Max interrupts 

XX 


Task state xxxx 

Last exchange xxxx 

Task flags xx 

Int Level xx 

Slave number xx 


Kernel saved ss:sp xxxx;xxxx 


Figure 4-11. Format Of VT Output (Interrupt Task) 


The fields in Figures 4-10 and 4-11 are as follows: 


Static pri 


Dynamic pri 


Task state 


Suspend depth 


Delay req 


Last exchange 


The current priority of the task. This value was 
set when the task’s containing job was created. 

A temporary priority that the Nucleus sometimes 
assigns to the task in order to Improve system 
perf ormanc e. 


The state of the task. The five possible states, 
as they are displayed, are: 


State 

ready 

asleep 

SUSP 

aslp/susp 

deleted 


Description 

ready for execution 

task is asleep 

task is suspended 

task is both asleep and suspended 

task is being deleted 


If this field contains an Invalid value, the 
System Debugger displays the value follov7ed by a 
space and two question marks. 

The number of RQ!?SUSPEND$TASK system calls that 
have been applied to this task without 
corresponding RQ$RESUME$TASK system calls. 

The number of sleep units the task requested when 
it last specified a delay at a mailbox or 
semaphore, or when it last called RQ$SLEEP. If 
the task has not done any of these things, this 
field contains 0„ 


The token for the mailbox, region, or semaphore 
at which the task most recently began to wait. 
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Except handler 


Except mode 


Task flags 


Containing job 
Interrupt task 


Kernel saved ss:sp 


Int level 


Master mask 


The start address of the job’s default 
exception handler. This value was set 
either when the task was created, by means 
of RQ$CREATE$TASK or RQ$CREATE$JOB , or later 
by means of RQ$SET$EXCEPTION$HANDLER. 

The value used to indicate the exceptional 
conditions under which control is to be 
passed to the new task’s exception handler. 
This value was set either when the task was 
created, by means of RQ$CREATE$TASK or 
RQ$CREATE$ JOB , or later by means of 
RQ$SET$EXCEPTION$HANDLER. 

The task flags parameter used when the task 
was created with the RQ$CREATE$TASK system 
call. 

The token of the job that contains this task. 

"No" signifies that the task is not an 
Interrupt task. In this case, there are no 
fields following this field in the display. 
(See Figure 4-10.) 

"Yes" signifies that the task is an 
interrupt task. In this case, there are 
additional fields in the display. (See 
Figure 4-11.) 

The contents of the ss:sp registers when the 
task last left the ready state. 

The level that the Interrupt task services. 
This level was set when this task called 
RQ$SET$INTERRUPT. 

The value associated with the Interrupt mask 
for the master interrupt controller. This 
value represents the master Interrupt levels 
that are disabled by virtue of the Interrupt 
level that the task services. For example, 
if the task services Interrupt level 51 (in 
octal) , then master levels 6 and 7 are 
disabled, so the master mask field is 
IIOOOOOOB (=C0H). For more information 
concerning interrupt levels, see the IRMX 86 
NUCLEUS REFERENCE MANUAL. 
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Slave mask The value associated with the Interrupt mask 

for a slave interrupt controller. This 
value represents the slave Interrupt levels 
that are disabled by virtue of the level 
that the task services. For example, if the 
task services interrupt level 51 (octal), 
then slave levels 2 through 7 are disabled, 
so the slave level field is llllllOOB 
(=FCH). For more Information concerning 
interrupt levels, see the IRMX 86 NUCLEUS 
REFERENCE ]^UAL. 

Slave number The programmable interrupt controller number 

of the slave that is referred to by the 
slave mask. This value depends entirely 
upon the interrupt level that the task 
services. If the value in the Int level 
field (after conversion to octal) is xy, 
then y+1 is the value in this field. 

Pending int The number of RQ$SIGNAL$INTERRUPT calls that 

are pending for this level. 

Max interrupts The maximum number of RQ$SIGNAL$INTERRUPT 

calls that can be pending for this level. 


MAILBOX DISPLAY 

The System Debugger displays Information about mailboxes in three 
different ways. The first display appears when nothing is queued at the 
mailbox, the second appears when tasks are queued at the mailbox, and the 
third appears when objects are queued at the mailbox. The formats of the 
three types of display are shown in Figures 4-12, 4-13, and 4-14. 


Object type = 3 Mailbox 


Task queue head 

xxxx 

Object queue head xxxx 

Queue discipline 

XX XX 

Object cache depth xxxx 

Containing job 

xxxx 


Figure 4-12. 

Format Of VT Output 

(Mailbox With No Queue) 
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Object type = 3 Mailbox 

Task queue head xxxx 
Queue discipline xxxx 
Containing job xxxx 


Task queue 


xxxx xxxx 


Object queue head xxxx 

Object cache depth xxxx 


Figure 4-13. Format Of VT Output (Mailbox With Task Queue) 


Object type = 3 Mailbox 

Task queue head xxxx 
Queue discipline xxxx 
Containing job xxxx 


Object queue 


xxxx xxxx • • • 


Object queue head xxxx 

Object cache depth xxxx 


Figure 4-14, Format Of VT Output (Mailbox With Object Queue) 


The fields in Figure 4-12, 4-13, and 4-14 are as follows: 


Task queue head 


Object queue head 


Queue discipline 


Object cache depth 


Containing job 


The token for the task at the head of the 
queue* If the task queue for this mailbox 
is empty, this field contains 0* 

The token for the object at the head of the 
queue. If the object queue for this mailbox 
is empty, this field contains 0. 

The manner in which tasks are queued at the 
mailbox. Tasks are queued 
"f Irst-in/f irst-out " (FIFO) or by priority 
(PRI), depending upon how the mailbox was 
specified to RQ$CREATE$MAILBOX. 

The size of the high performance portion of 
the object queue that is associated with the 
mailbox. This size was specified when the 
mailbox was created with RQ$CREATE$MAILBOX. 

The token for the job that contains this 
mailbox. 
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Task queue A list of tokens for the tasks queued at the 

mailbox in the order in which tasks are queued. 
If no tasks are queued at the mailbox, this list 
does not appear. 

Object queue A list of tokens for the objects queued at the 

mailbox in the order in which the objects are 
queued. If no objects are queued at the 
mailbox, this list does not appear. 


SEMAPHORE DISPLAY 


The System Debugger displays information about semaphores in two ways. The 
first display appears when no tasks are queued at the semaphore, and the 
second appears when tasks are queued at the semaphore. The formats for the 
two types of displays are shown in Figures 4-15 and 4-16. 


Object type = 4 

Semaphore 



Task queue head 

xxxx 

Queue discipline 

XXX 

Current value 

XX XX 

Maximum value 

xxxx 

Containing job 

xxxx 



Figure 4-15 

. Format Of VT Output 

(Semaphore With No 

Queue) 


Object type = 4 

Semaphore 



Task queue head 

xxxx 

Queue discipline 

XXX 

Current value 

xxxx 

Maximum value 

xxxx 

Containing job 

xxxx 



Task queue 

xxxx xxxx ... 



Figure 4-16. 

Format Of VT Output 

(Semaphore With Task Queue) 


The fields in Figures 4-15 and 4-16 are as follows: 

Task queue head The token for the task at the head of the queue. 
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Queue discipline The manner in which tasks are queued at the 

semaphore. The tasks are queued 
"first-in/first-out" (FIFO) or by priority 
(PRI), depcmding upon how the semaphore was 
specified v/hen created with RQ$CREATE$ SEMAPHORE. 

Current value The number of units currently held by the 

semaphore. 

Maximum value The maximum number of units the semaphore can 

hold. This number was specified when the 
semaphore V7as created with RQ$CREAT E$ SEMAPHORE . 

Containing job The token for the job that contains the 

semaphore. 

Task queue A list of tokens for the tasks queued at the 

semaphore, in the order in which the tasks are 
queued there. If no tasks are queued at the 
semaphore, this list does not appear. 


REGION DISPLAY 

If the parameter that you supply is a valid token for a region, the System 
Debugger displays information about the associated region as shown in 
Figure 4-26. 


Object type = 5 Region 

Entered task xxxx Queue discipline xxxx 

Containing job xxxx 

Task queue xxxx xxxx ... 


Figure 4-17. Format Of VT Output (Region) 


The fields in Figure 4-17 are as follows: 

Entered task The token for the task that is currently 

accessing Information guarded by the region. 

Queue discipline The manner in which tasks are queued at the 

region. The tasks are queued first-in/first-out 
(FIFO) or by priority (PRI), depending upon how 
the region was specified when created with 
RQ$CREATE$REGION. 
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Containing job The token for the job that contains the region. 

Task queue Tokens for the tasks waiting to gain access to 

data guarded by the region. This line Is 
displayed only If a task already has access to 
the data guarded by the region. 


SEGMENT DISPLAY 


If the parameter that you supply Is a valid token for a segment, the System 
Debugger displays Information about the associated segment as shown In 
Figure 4-18. 


Object type = 6 segment 

Num of paragraphs xxxx Containing job xxxx 


Figure 4-18. Format Of VT Output (Segment) 


The fields In Figure 4-18 are as follows: 

Num of paragraphs The number of 16 -byte paragraphs In this 

segment. The size of the segment was specified 
when the segment was created with the 
RQ$CREATE$SEi3MENT system call. 

Containing job The token for the job that contains the segment. 


EXTENSION OBJECT DISPLAY 


If the parameter that you supply Is a valid token for an extension, the 
System Debugger displays Information about the associated extension as 
shown In Figure 4-19. 


Object type = 7 Extension 

Extension type xxxx Deletion mailbox xxxxx 

Containing job xxxx 


Figure 4-19. Format Of VT Output (Extension Object) 
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The fields in Figure 4-19 are as follows: 

Extension type The type code associated with composite objects 

licensed by this extension. This code was 
specified when the RQ$CREATE$ EXTENSION system 
call, was used to create this extension type. 

See the iRMX 86 NUCLEUS REFERENCE MANUAL for more 
information concerning extension types. 

Deletion mailbox The token for the deletion mailbox associated 

with this extension. This mailbox was specified 
when the RQ$CREATE$EXTENSION system call was used 
to create this extension type. 

Containing job The token for the job that contains the extension. 


COMPOSITE OBJECT DISPLAY 

There are five kinds of composite displays. The first kind depicts all 
composites except those defined in the Basic I/O System (BIOS). The second 
kind depicts BIOS user objects. The remaining kinds depict BIOS physical, 
stream, and named file connections. 

The format for the display of non-BIOS objects is as shown in Figure 4-20. 


Object type = 8 Composite 


Extension type 

xxxx 

Extension obj 

xxxx Deletion 

mbox 

xxxx 

Containing job 

xxxx 

Num of entries 

xxxx 



Component list 

xxxx 

xxxx xxxx 

xxxx . . . 



Figure 4-20. 

Format 

Of VT Output (Composite Object Other 

Than 

BIOS) 


The fields in Figure 4-20 are as follows: 

Extension type The code for the extension type of the 

extension object used to create this 
composite. This code was specified when the 
extension object was created with 
RQ$CREATE$EXTENSION . 

Extension obj The token for the extension object used to 

create this composite object. 
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Deletion mbox 

The token for the mailbox to which this 
composite goes when the composite is to be 
deleted. This mailbox was specified when 
the extension was created with 
RQ$CREATE$EXTENSION. 

Containing job 

The token for the job that contains the 
composite object. 

Num of entries 

The number of component entries in the 
composite object. 

Component list 

The list of tokens for the components of the 
composite.. 

The format for the Basic 
Figure 4-21. 

I/O System user object display is shown in 


Object type = 8 Composite 


Extension type xxxx Extension obj xxxx Deletion mbox xxxx 

Containing job xxxx Num of entries xxxx 

BIOS USER OBJECT: 

User segment xxxx Number of IDs xxxx 

User ID list xxxx xxxx ••• 

Figure 4-21. Format Of VT Output (BIOS User Object Composite) 


The new fields Introduced in Figure 4-21 are as follows: 

User segment The token for the segment containing the 

user IDs for the user object. 

Number of IDs The number of user IDs associated with the 

user object. 

User ID list List of the user IDs associated with the 

user object. 

The format for a (file) connection to a physical file is shown in Figure 
4-22. 
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Object type = 8 Con 5 )oslte 


Extension type xxxx Extension obj xxxx Deletion mbox xxxx 

Containing job xxxx Num of entries xxxx 


T$CONNECTION OBJECT 
File driver Physical Conn flags 

Open mode xxxx 

lORS cache xxxx 

Dynamic DUIB xxxxx 
Num of readers xxxx 
File drivers xxxx 

Device functs xxxx 


Open share 
File node 
DUIB pointer 
Num of writers 
Device gran 
Num dev conn 


XX 

xxxx 

xxxx 

xxxx: xxxx 
xxxx 
xxxx 
xxxx 


Access 
File pointer 
Device desc 
Num of conn 
File share 
Device size 
Device name 


xxxx 

xxxxxxxx 

xxxx 

xxxx 

xxxxxxx 

xxxxxxxx 

xxxxxxxxxx 


Figure 4-22. Format Of VT Output (Physical File Connection) 


The new fields Introduced in Figure 4-22 are as follows: 

File driver The BIOS file driver to which this connection is 

attached. The three possible values are physical, 
stream, and named. If this field contains an 
invalid value, the System Debugger displays the 
value followed by a space and two question marks. 

Conn flags The flags for the connection. If bit 1 is set to 

one, this connection is active and can be opened. 
If bit 2 is set to one, this is a device 
connection. (Bit 0 is the low-order bit.) 

Access The access rights for this connection. This 

display uses a single character to represent a 
particular access right. If the file has the 
access right, the character appears. However, if 
the file does not have the access right, a hyphen 
(-) appears in the character position. The access 
rights, along with the characters that represent 
them, are as follows: 



Directory files: 


DLAC 


Delete 

List 

Add 

Change 


Data Files: 


DRAU 

I I Update 

' Append 

Read 

Delete 
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open mode 


Open share 


File pointer 
lORS cache 

File node 
Device desc 


The mode established when this connection was 
opened. The possible values are: 


Open Mode 
Closed 
Read 
Write 
R/W 


Description 
Connection is closed 
Connection is open for reading 
Connection is open for writing 
Connection is open for reading 
and writing 


If this field contains an invalid value, the 
System Debugger displays the value, followed by a 
space and two question marks. If this value is 
Read, Write, or R/W, this value was specified 
when the connection was opened. 


The sharing status established for this 
connection when it was opened. The sharing 
status for a connection is a subset of the 
sharing status of the file (see the File share 
field). The possible values are: 


Share Mod e 
Private 
Re aders 
Writers 
ALL 


Description 

Private use only 

File can be shared with readers 

File can be shared with writers 

File can be shared with all 

users 


If the connection is not open, then 0 is 
displayed. If this field contains an invalid 
value, the System Debugger displays the value, 
followed by a space and two question marks. This 
probably indicates that the connection data 
structure has been corrupted. 

The current location of the file pointer for this 
connection. 

The token for the segment at the head of the BIOS 
list of used lORS's. These lORS’s are being 
saved for the ELQ$WAIT$IO system call to use 
again. The list is empty if 0000 appears in this 
field. 

The token for a segment that the Operating System 
uses to maintain information about the 
connection. The information in this segment 
appears in the next two fields. 

The token for the segment that contains the 
device descriptor. The device descriptor is used 
by the Operating System to maintain information 
about the connections to the device. 
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Dynamic DUIB 


DUIB pointer 


Num of conn 
Nura of readers 

Num of writers 

File share 


File drivers 


Indicates whether a DUIB was created dynamically 
when the device associated with this connection 
was attached. 

The address of the Device Unit Information Block 
(DUIB) for the device unit containing the file. 
See the GUIDE TO WRITING DEVICE DRIVERS FOR THE 
mMX 86 AND IRMX 88 I/O OPERATING SYSTEMS for 
more information about the DUIB. 

Tlie number of connections to the file. 


The number of connections to the file that are 
currently open for reading. 

The number of connections to the file that are 
currently open for writing. 

The share mode of the file. This parameter 
defines how other connections to the file can be 
opened. The share mode of a file is a superset 
of the sharing status of each of the connections 
to the file (see the Open share field). The 
possible values are: 


Share Mode 
Private 
Readers 
Writers 
ALL 


Description 

Private use only 

File can be shared with readers 

File can be shared with writers 

File can be shared with all users 


If this field contains an Invalid value, the 
System Debugger displays the value, followed by a 
space and two question marks. This probably 
means that the internal data structure for the 
file or the fnode for the file has been 
corrupted. See the iRMX 86 BASIC I/O SYSTEM 
REFERENCE MANUAL for more information about 
sharing modes for files and connections. 

The file drivers that- the file can be connected 
to. If the file can be connected to a file 
driver, then the bit in the display is set to 1. 
Bit 0 is the rightmost bit. 


Bit Driver 

0 Physical file 

1 Stream file 

2 reserved 

3 Named file 
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Device gran The granularity (in bytes) of the device. This 

is the minimum number of bytes that can be 
written to or read from the device in a single 
(physical) I/O operation. 


Device size 


The capacity (in bytes) of the device. 


Device functs Describes the functions supported by the device 

on which this file resides. Each bit in the 
low-order byte of the field corresponds to one of 
the possible device functions. If that bit is 
set to 1, then the corresponding function is 
supported by the device. 


Bit 

0 

1 

2 

3 

4 

5 

6 
7 


Function 

F$READ 

F$WRITE 

F$SEEK 

F$SPECIAL 

F$ATTACH$DEV 

F$DETACH$DEV 

F$OPEN 

F$CLOSE 


Num dev conn 


The number of connections to the device. 


Device name 


The 14- (or fewer) character name of the device 
where this file resides. 


The format for a (file) connection to a stream file is shown in Figure 
4-23. 


Object type = 8 Composite 

Extension type xxxx Extension obj xxxx Deletion mbx xxxx 

Containing job xxxx Num of entries xxxx 


T$ CONNECTION OBJECT 


File driver 

St ream 

Conn -flags 

XX 

Access 

xxxx 

Open mode 

xxxx 

Open share 

xxxx 

File pointer 

xxxxxxxx 

lORS cache 

xxxx 

File node 

xxxx 

Device desc 

xxxx 

Dynamic DU IB 

xxxxx 

DUIB pointer 

xxxx: xxxx 

Num of conn 

xxxx 

Num of readers 

xxxx 

Num of writers 

xxxx 

File share 

xxxxxxx 

File drivers 

xxxx 

Device gran 

xxxx 

Device size 

xxxxxxxx 

Device functs 

xxxx 

Num dev conn 

xxxx 

Device name 

xxxxxxxxxx 

Req queued 

xxxx 

Queued conn 

xxxx 

Open conn 

xxxx 


Figure 4-23. Format Of VT Output (Stream File Connections) 
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The new fields introduced in Figure 4-23 are as follows: 

Req queued The number of requests that are currently 

queued at the stream file. 

Queued conn The number of connections that are currently 

queued at the stream file. 

Open conn The number of connections to the stream file 

that are currently open. 

The format for a named (file) connection display is shox^m in Figure 4-24. 


Object type = 8 Composite 


Extension type 

XX XX 

Extension obj 

xxxx 

Deletion mbx 

xxxx 

Containing job 

xxxx 

Num of entries xxxx 



T$CONNECTION OBJECT 




File driver 

Named 

Conn flags 

XX 

Access 

xxxx 

Open mode 

xxxx 

Open share 

xxxx 

File pointer 

xxxxxxxx 

lORS cache 

xxxx 

File node 

xxxx 

Device desc 

xxxx 

Dynamic DUIB 

xxxxx 

DUIB pointer 

XXX X : xxxx 

Num of conn 

xxxx 

Num of readers 

xxxx 

Num of writers 

xxxx 

File share 

xxxx 

File drivers 

xxxx 

Device gran 

xxxx 

Device size 

xxxxxxxx 

Device functs 

xxxx 

Num dev conn 

xxxx 

Device name 

xxxx 

Num of buffers 

xxxx 

Fixed update 

xxxx 

Update timeout 

xxxx 

Fnode number 

xxxx 

File type 

xxxx 

Fnode flags 

xxxx 

Owner 

xxxxx 

Flle/Vol gran 

xxxx 

Fnode PTR(s) 

xxxx: xxxx 

Total blocks 

xxxxxxxx Total size 

xxxxxxxx 

This size 

xxxxxxxx 

Volume gran 

xxxx 

Volume size 

xxxxxxxx 

Volume name 

xxxxx X 

Figure 

4-24. 

Format Of VT Output (Named File Connection) 



The new fields Introduced in Figure 4-24 are as follows: 

Num of buffers The number of buffers allocated for blocking 

and unblocking I/O requests involving the 
device. A value of 0 indicates that the 
device is not a random-access device. 

Fixed update Indicates whether the device uses the fixed 

update feature. For more information about 
fixed updating, see the iRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL. 


System Debugger 4-45 


COMMANDS 





COMMANDS 


VT-DISPLAYiRMX™ 86 OBJECT 


Update timeout 

Fnode number 
File type 

Fnode flags 


Owner 

File/Vol gran 
Fnode PTR(s) 

Total blocks 


The length of the timeout for the update 
timeout feature, measured in Nucleus time 
units. For more information about update 
timeout, see the IRMX 86 BASIC I/O SYSTEM 
REFERENCE MANUAL. 

The fnode number of this file. For more 
Information about fnodes , see the IRMX 86 
DISK VERIFICATION UTILITY REFERENCE MANUAL. 

The type of named file. The possible values 
are: 


File type 
DIR 
DATA. 
SPACEMAP 
FNODEMAP 
BADBLOCKMAP 


Description 
Directory file 
Data file 

Volume free space map file 
Free fnodes map file 
Bad blocks file 


A word containing flag bits. If a bit is 
set to 1, the following description 
applies. Otherwise, the description does 
not apply. (Bit 0 is the low-order bit.) 


Bit 

0 

1 

2 

3-4 

5 

6 

7-15 


Description 

This fnode is allocated 
The file is a long file 
Primary fnode 
Reserved 

This file has been modified 
This file is marked for deletion 
reserved 


The ID of the owner of the file. If this field 
has a value of FFFF , then the field is 
Interpreted as "World." See the IRMX 86 BASIC 
I/O SYSTEM REFERENCE MANUAL for more 
information about owners of files. 


The granularity of the file (in volume 
granularity units). 

The values of the fnode pointers. See the 
IRMX 86 DISK VERIFICATION UTILITY REFERENCE 
MANUAL for more Information about fnode 
pointers. 


The total number of volume blocks currently 
used for the file; this includes indirect 
blocks. See the IRMX 86 DISK VERIFICATION 
UTILITY REFERENCE MANUAL for more information 
about blocks. 
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Total size 


This size 

Volume gran 
Volume size 
Volume name 


The total size (in bytes) of the file; this 
includes actual data only. See the IRMX 86 
DISK VERIFICATION UTILITY REFERENCE MANUAL for 
more Information. 

The total number of bytes allocated to the file 
for data. See the IRMX 86 DISK VERIFICATION 
UTILITY REFERENCE MANUAL for more Information. 

The granularity (in bytes) of the volume. 

The size (in bytes) of the volume. 

The name of the volume. 
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VU — Display The System Calls In A Task's Stack 

The VU command displays (unwinds) the IRMX 86 system calls in the stack of 
the task whose token you enter. 



PARAMETER 

token The token for the task whose stack is to be 

searched for system calls. 


DESCRIPTION 

The VU command accepts a token for a task and then searches the task's 
stack for IRMX 86 system calls, starting at the top of the stack. For 
each system call it finds there, it displays two things: 

• The address of the next Instruction to be executed on behalf of 
the task after the system call has finished running. This is the 
return address for the call. 

• The VS display with two lines of stack values (or more if 
required for parameters), as if the CALL instruction for the 
system call were in the CS:IP register and the displayed stack 
values were at the top of the stack. 

This command requires that the task stack reside inside an IRMX 86 segment. 

The VU command uses internal IRMX 86 data structures to get some of its 
information. Immediately after the system call at the top of the task's 
stack runs to completion, the data structures are updated. Therefore, 
there is a brief moment when the Information the VU command uses is 
obsolete. This means that it is possible, although unlikely, that the 
first system call the VU command displays is not valid. 

Figure 4-25 illustrates the format of one system call display by the VU 
command. System calls can be nested, with one calling another, so some 
invocations of the VU command produce multiple displays of the type shown 
in the figure. The example that follows Illustrates this. 

If there are no system calls in the stack of the indicated task, the VU 
command displays the message: 

No system calls on stack 
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Return cs:ip 

- yyyy:yyyy 







xxxx:xxxx 

xxxx xxxx 

xxxx 

xxxx 

xxxx 

xxxx 

xxxx 

xxxx 

xxxxtxxxx 

xxxx xxxx 

xxxx 

xxxx 

xxxx 

xxxx 

xxxx 

xxxx 

S/W int: xx 

(subsystem) 

entry 

code 

xxxx 

system 

call 



rparameters. : 


Figure 4-25, Format Of VU Output 


The fields in Figure 4-25 are as follows: 


Return cs:ip 

The return address for the system call of this 
display. 

xxxx: xxxx 

The address of the (top of the) portion of the 
stack that is devoted to this call* 

xxxx 

Stack values. 

parameters 

The parameter names associated with the stack 
values. The parameters correspond to the stack 
values directly above them. 

S/W int: xx 
(subsystem) 

Tlie software Interrupt number for this call and 
the iRMX 86 subsystem corresponding to that number 

entry code xxxx 

Tlie entry code for the system call within the 
subsystem. 

system call 

The name of the iRMX 86 system call. 


ERROR MESSAGES 

The System Debugger returns the following error messages for the VU 
command. 


Error Message 
Syntax Error 

*** INVALID TASK TOKEN *** 

Stack not in an iRMX 86 segment 


Description 

You made an error in entering the 
command. 

The value you entered for the token 
is not a valid task token. 

The stack of the indicated task is 
not in an iRMX 86 segment, as is 
required. 
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EXAMPLE 


This example shows how the VU command responds when system calls are 
nested. The task for the example has called RQ$S$WRITE$MOVE of the 
Extended I/O System. RQ$S$WRITE$MOVE has called RQ$A$WRITE of the Basic 
I/O System. And RQ$A$WRITE has called RQ$RECEIVE$MESSAGE to wait for the 
data transfer to be completed. 

Before the message arrives signalling the completion of the transfer, the 
VU command is invoked, as follows: 

.VU ???? 


The System Debugger responds by displaying the following: 


Return cs:ip - 0104: 57 6A 


416A:01B2 

01C8 

416A 

OICC 

416A 

FFFF 

376E 

8763 

2988 

416A;01C2 

1550 

0000 

71 9E 

2FF9 

3440 

E55E 

5000 

DD54 

S/W Int: B8 

(Nucleus) Entry code 

0303 

Receive message 



: . . .excep$p. . . 


p$p. . . 

: .time. : 

; .mbox. : 



Return cs:ip 

- 1756:08e7 







416A:01D4 

OlEA 

416A 

3F56 

0400 

0000 

42E9 

429A 

7866 

416A:01E4 

1430 

5246 

OlFE 

22F9 

1400 

021D 

0000 

OlFE 

S/W Int: CO 

(BIOS) 

Entry 

code OOOE 

Write 





: . . .excep$p. . . 

: .mbox. : 

> coun t 

;: . .buf fer$p. . . : . 

.conn. : 


Return cs:ip 

- 3A98 

:0 6FA 







416A:0218 

0020 

39F4 

0400 

0034 

39f4 

429A 

5A8 4 

9344 

416A:0228 

4456 

0000 

0000 

C7C7 

C7C7 

C7C7 

C7C7 

C7C7 


S/W Int: Cl (EIOS) Entry code 0101 Write move 

: . . .excep$p. . . : .count: .. .buf fer$p. . . : .conn. : 
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